DOCS: Add examples to Triangle methods and properties (#704)#719
Merged
kennethshsu merged 1 commit intocasact:mainfrom Apr 29, 2026
Merged
Conversation
Adds doctest-validated Examples blocks to 19 Triangle methods and properties, matching the Polars-style format used in the constructor PR: no imports, "..." continuation lines, and strict output indentation. Methods with Examples added to existing docstrings: incr_to_cum, cum_to_incr, dev_to_val, val_to_dev, grain, trend, shift, sort_axis, development_correlation, valuation_correlation. Properties with Examples added to existing docstrings: link_ratio, is_full. Properties with full docstrings written from scratch: age_to_age, is_ultimate, is_pattern, is_val_tri, latest_diagonal, origin, development. All 19 example blocks validated with strict doctest (no NORMALIZE_WHITESPACE flag). Also adds .scratch/ to .gitignore for local handoff notes and throwaway verification scripts.
EKtheSage
requested review from
genedan,
henrydingliu,
jbogaardt and
kennethshsu
as code owners
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #719 +/- ##
=======================================
Coverage 85.12% 85.12%
=======================================
Files 85 85
Lines 4909 4909
Branches 629 629
=======================================
Hits 4179 4179
Misses 521 521
Partials 209 209
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
kennethshsu
approved these changes
Apr 29, 2026
kennethshsu
pushed a commit
that referenced
this pull request
Apr 29, 2026
Adds doctest-validated Examples blocks to the five deterministic IBNR estimator classes, matching the Polars-style format used in PRs #714 and #719: no imports, "..." continuation lines, strict output indentation, and byte-exact output (no NORMALIZE_WHITESPACE). Per-class coverage: - Chainladder: class docstring, fit, predict - MackChainladder: class docstring, fit, predict (predict had no docstring before this PR), and five property docstrings written from scratch: full_std_err_, total_process_risk_, mack_std_err_, total_mack_std_err_, summary_ - BornhuetterFerguson: class docstring, fit, predict. Class docstring notes the apriori-as-Triangle requirement (a literal int sample_weight raises AttributeError) and explains the canonical "cl_ult * 0 + value" broadcasting idiom for building a flat per-origin apriori - Benktander: class docstring, fit, predict. Class docstring shows that n_iters interpolates between BF (n_iters=1) and chainladder (n_iters large) - CapeCod: class docstring, fit, predict. Class docstring contrasts CapeCod with BF/Benktander (sample_weight is exposure, apriori is derived) and demonstrates the trend and decay parameters All 20 example blocks validated with strict doctest.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What does this pull request do?
Addresses #704 for the
Triangleclass methods and properties (the second tranche after #714, which covered the constructor).Adds doctest-validated
Examplesblocks to 19 Triangle methods and properties, using the same Polars-style format established in #714: noimportstatements,...continuation prefixes, and strict output indentation at the same base level as>>>.Methods (Examples added to existing docstrings)
incr_to_cum,cum_to_incrdev_to_val,val_to_devgraintrendshift,sort_axisdevelopment_correlation,valuation_correlationProperties (Examples added to existing docstrings)
link_ratio,is_fullProperties (full docstrings written from scratch)
These had no docstring or only a one-line description before this PR:
age_to_age(alias oflink_ratio)is_ultimate,is_pattern,is_val_trilatest_diagonalorigin,developmentData choices
cl.load_sample('ukmotor')is used as the default 7x7 cumulative example data. Its width fits cleanly inside a docstring and matches the convention used elsewhere in the package.cl.load_sample('raa')is used fordevelopment_correlation/valuation_correlationsince it is the canonical Mack 1997 dataset.incr_to_cum, OQDQ forgrain, small numeric examples fortrend/shift).bool(...)to extract the underlying value, since the properties return numpy booleans whose repr isnp.True_/np.False_.Validation
All 19 example blocks were executed with Python's
doctestmodule in strict mode (noNORMALIZE_WHITESPACEflag) and pass with byte-exact output comparison.Other
Adds
.scratch/to.gitignorefor local handoff notes and throwaway verification scripts.Relevent Github ticket(s)?
Issue #704. Companion to PR #714 (constructor examples).
Note
Low Risk
Changes are docstring-only (plus
.gitignore) and do not modify runtime logic, so functional risk is minimal; main risk is doc build/doctest formatting issues.Overview
Expands
TriangleAPI documentation by adding/new-writing detailed docstrings with doctest-styleExamplesfor key properties (origin,development,is_val_tri,is_pattern,is_ultimate,latest_diagonal,age_to_age) and for methods includingincr_to_cum,cum_to_incr,dev_to_val,val_to_dev,grain,trend,shift,sort_axis,development_correlation, andvaluation_correlation.Also updates
.gitignoreto include a local.scratch/directory (and normalizes the.ideaignore entry).Reviewed by Cursor Bugbot for commit 4a07452. Bugbot is set up for automated code reviews on this repo. Configure here.